﻿//-----------------------------------------------------------------------------------------
// <copyright file="ProximitySensor.cs" company="Jakub Florczyk (www.jakubflorczyk.pl)">
//      Copyright © 2009 Jakub Florczyk (www.jakubflorczyk.pl)
//      http://samsungmobilesdknet.codeplex.com
// </copyright>
//-----------------------------------------------------------------------------------------

namespace SamsungMobileSDKNET
{
    using System.Runtime.InteropServices;

    /// <summary>
    /// Function signature for proximity sensor event handler.
    /// </summary>
    /// <param name="objectIsNear">BOOL that receives TRUE if the proximity sensor detects the presence of an object nearby, FALSE otherwise.</param>
    public delegate void ProximitySensorEventHandler(bool objectIsNear);

    /// <summary>
    /// Samsung Proximity Sensor API.
    /// </summary>
    /// <remarks>
    /// The Proximity Sensor API enables you to utilize the capabilities of the proximity sensor, which can detect the presence of nearby objects without any physical contact. The API can be used to determine if an object is currently nearby, or get notifications by callback when an object moves nearby or away.
    /// </remarks>
    public class ProximitySensor
    {
        /// <summary>
        /// Returns whether the proximity sensor detects an object nearby.
        /// </summary>
        /// <param name="objectIsNear">A pointer to a BOOL that receives TRUE if the proximity sensor detects the presence of an object nearby, FALSE otherwise.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if bObjectIsNear is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the proximity sensor is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiProximitySensorIsObjectNear")]
        public static extern ResultCode IsObjectNear(
            [Out] out bool objectIsNear);

        /// <summary>
        /// Registers a handler to be called when the proximity sensor value changes. Subsequent registrations from the same process replace the previous handler.
        /// </summary>
        /// <param name="handler">A callback function.</param>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorInvalidParameter"/> if handler is NULL
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures 
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiProximitySensorRegisterOnChangeHandler")]
        public static extern ResultCode RegisterOnChangeHandler(
            [In] ProximitySensorEventHandler handler);

        /// <summary>
        /// Unregisters the handler that was registered by a previous call to the <see cref="M:SamsungMobileSDKNET.ProximitySensor.RegisterOnChangeHandler"/> function.
        /// </summary>
        /// <returns>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.Success"/> on success
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorDeviceNotFound"/> if the device is not present or supported
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorCannonActivateServer"/> if the sensor server cannot be started
        /// <br/>
        /// <see cref="F:SamsungMobileSDKNET.ResultCode.ErrorUnknown"/> for all other failures
        /// </returns>
        [DllImport(Common.DllName, EntryPoint = "SmiProximitySensorUnregisterOnChangeHandler")]
        public static extern ResultCode UnregisterOnChangeHandler();
    }
}
